home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / PROTO212.ARJ / DOCUMENT.EXM next >
Text File  |  1992-01-24  |  4KB  |  78 lines
  1.     The file example.zip holds several files. We will try to
  2.     present what the documentation tools are. In this text, the
  3.     word documentation refers to whatever tools help programmers
  4.     understand and use software libraries. We are not talking
  5.     about user documentation.
  6.  
  7.     Providing a reliable documentation on a software system
  8.     is not easy. Most methodologies based on system too far
  9.     away from the source code won't work.
  10.  
  11.     Reliable documentation on a system helps code reusability.
  12.     Here is, we believe, the most important things to do for code
  13.     reuse to happen.
  14.  
  15.     A)  Software component must be easy to locate. Programmers
  16.         need index, summary, reference guides ... If a component
  17.         exists but is not easy to locate, it will be duplicated.
  18.  
  19.     B)  Software component must be easy to understand.
  20.  
  21.         Each function of a system must be documented, simply and
  22.         that documentation must be near the code itself.
  23.  
  24.     C)  The code must work well !
  25.  
  26.     The Solucorp Programmer's Toolkit start from a simple principle.
  27.     Reliable documentation for a software component (function) is
  28.     in the source code, immediatly near the declaration part of the
  29.     component. If this documentation is not reliable, then nothing
  30.     will ever be.
  31.  
  32.     The guidelines are simple. The first line of comments before a
  33.     function declaration is a short description of the function
  34.     action. All following comments before the declaration should
  35.     tell explicitly what the function does, when a programmer must
  36.     use it, what would make this function better, what values are
  37.     returned, and so on.
  38.  
  39.     The source files (source*.c) provided show a sample system with
  40.     very short documentation. In the provided makefile, a target
  41.     "doc" at the end, shows which commands are used to update the
  42.     documentation kit.
  43.  
  44.     From the source file, proto (the prototype extractor) gets
  45.     the prototypes and surrounding comments. The file xsys.nap
  46.     is produced.
  47.  
  48.     Naperm format three files from xsys.nap.
  49.  
  50.     xsys.nas : All functions are presented with the short documentation.
  51.     xsys.nai : This is a permutted index of the file xsys.nas.
  52.     xsys.nah : This is a log of all revisions made to project xsys.
  53.                It shows when functions has been added, modified or
  54.                deleted from system xsys.
  55.  
  56.     Those three files are good to spot a function when you have
  57.     at least a small experience with system xsys. If you are
  58.     new to xsys, and the system has over a hundred functions, you
  59.     need something else. You need a general document that introduces
  60.     xsys and present function is an organised way. This kind of
  61.     document is difficult to produce. It is generally huge. It
  62.     is often inacurate. For all this, it is also never read.
  63.  
  64.     There is a way out. If you have acurate documentation in
  65.     the source files for each function, then there is a way
  66.     to create this document without too much pain. The file
  67.     xsys.doc is the layout of the reference manual of system
  68.     xsys. It contains simple introduction, a general outline of
  69.     the system, and simple classification of the function of the
  70.     system.
  71.  
  72.     From xsys.doc and xsys.nap, the file xsys.ref is produced.
  73.     This file is the reference manual. It is always up to date.
  74.     Nadoc is the utility that produced that. It will spot all
  75.     functions not classified in xsys.doc. It will also
  76.     tell about functions that do not exist anymore.
  77.  
  78.